Copyright: Visual Help Copyright® 1993 Firas Bushnaq


Component Builder for Delphi

• How to build a component

• What Component Builder is (and is not)

• Product Support

• How to register

• Frequently Asked Questions

• Miscellaneous

• About this help file

• Revision History

If you're new to component writing check out the For Beginners and Recommended reading topics in this help file.


For Beginners

 What is a component ?

 Why build components ?

 Recommended reading


WHAT IS A COMPONENT
What is a component ?

A component is a module of code whose interface is defined by properties, methods and events.  Still confused ? Let me give you an example:

I really HATE to write code to parse strings or text files.  The code is tedious and there are always bugs that have to be traced out through the debugger.  So... I wrote a component called TAwk.  It's job is to do that for me, no more coding a parsing function.  I just set a few properties such as the string to be parsed, the type of field separators I'll be looking for (such as a comma) and then call the execute method.  The component takes that information and gives me back in the form of another method call all the tokens in the string.  This is an example of a non-visual component.  Non-visual in that the component is never visible at run time, it's just an object that I can use in developing applications.  You can create visual and non-visual components.  A visual component is one that the application user does something with at run time, such as a button.


WHY BUILD COMPONENTS
Why Build Components ?

Components offer certain advantages in developing applications.  They are reusable. Once you've built the component you can use it over and over whenever it's designed functionality is called for.  Components also increase your productivity and encourage consistency and they're easier to use than writing code over and over.


Recommended Reading

Whether you're an experienced component writer or just a beginner you'll find a wealth of knowledge in Ray Konopka's book "Developing Custom Delphi Components".  Coriolis Group Books ISBN 1-883577-47-0.


website
www.mindspring.com/~jcta


How to Build a Component

If you write components for Delphi, you need Component Builder.  Component Builder speeds through the task of defining properties, methods and event handlers and creates an output source file that can be compiled and installed into the component library.  All you'll need to do is add the specific code to the methods and functions created by Component Builder and your component's done.

The entire process is accomplished in a few easy steps:

Step 1:

Define the component's class, ancestor and select the palette page

Step 2:

Define the component's properties

Step 3:

Define methods and message handlers

Step 4:

Define event handlers

Step 5:

Build output

Step 6:

Edit and add code if necessary

Step 7:

Save your work

See Also:

Installing New Components


Define the Component

The first step is creating your component is to define the class, ancestor and palette page.  By default, the unit name is 'unit1.pas'.  You can change this if you want, but be sure to include the path name as well.

1.	Define the class name you want to use for your component.  For example: TRotateLabel

2.	Select the ancestor. For Example: TComponent

3.	Select the Palette page for example 'Samples'


Defining Properties

The property name and data type are required.  All other property attributes are optional.  Defining a property is easy let's use an example to illustrate the process.  Suppose you want to construct a component that reads a text file and counts the number of lines in the file.  To do this we'll need a property to hold the line count, let's call it Count.  Also, we want this property to be read only and run time only since it has no value in design mode.  The following process is all that's necessary to define this property:

1.	Type in Count for the property name.

2.	Select the property data type as longint since there could be more than 32767 lines in the file.

3.	Check the check boxes for run time only and read only.

4.	Select Direct Access for read access.  You'll note that write access has been disabled since we              	checked read only.

5.	Click the Add button to add this property to the list of defined properties.

Note:

If you need to eliminate a previously defined property, select it from the list of Defined Properties and click the Remove button.

See Also:

Property Data Types

Property Access Methods

Runtime Only Properties

Read Only Properties

Write Only Properties

Protected Properties

Default Value

Removing Properties

Editing existing properties


Property Data Types

Select a data type from the list or enter a type that is not in the list.  A property can have a type that is not one of the simple types in the list, for example TStringList.


Property Access Methods

Properties can be accessed at run time by either of two methods:

Direct Access:

The property's value is either read or written by accessing the underlying variable directly.

Access Methods:

A function or procedure is used to access or set the value of the underlying variable for a property.

The Component Writer's Guide contains a detailed explanation of property access on pages 35-36.  The type of access will be determined by what the property is designed to do.


Runtime Only Properties

A property that is defined as runtime only will not appear in the Object Inspector when Delphi is in design mode.  The property may be accessed only at runtime.


Read Only Properties

A Read Only Property is exactly that 'Read Only'.  The property value cannot be changed and will not be visible in the Object Inspector while in design mode.


Write Only Properties

Write Only properties are rare.  By setting this attribute, the property's value can only be written, not read.


Protected Properties

Select the Protected attribute to make a property protected.  Refer to page 33 of the Component Writer's Guide.


Default Value

Enter the default property value if you need one.  Be sure that the value you enter is compatible with the data type you choose for the property.  For example, don't enter 'abc' with a data type of integer.


REMOVING PROPERTIES METHODS AND EVENTS
Removing Properties, Methods and Events

To remove a property, method or event handler that has been previously defined, select it from the list and click the remove button.  If you have previously done a build, you'll want to rebuild the output by clicking the Build button again.


Editing existing properties

Existing properties, methods and events can be edited by double clicking on the item in their respective list boxes.  When a property, method or event handler is selected by double clicking on it in the list box, the item is removed from the defined list and brought back to 'center stage' for editing.  You can then change any attributes, paramaters, etc. of the item and add it back to the list.


Defining Methods

To define a component method type in a name for the method, select the type (either function or procedure) give it the paramater list and if it is a function, select the type of data it returns.  Note that the paramater list should not include the parentheses, for example just   ' i : integer' is all that's needed (without the quotes of course).  The method declaration and code skeleton are built for you but of course you'll have to add the 'real' code the makes the method perform it's assigned task.  I'd love to be able to do that for you too, but I can't read your mind at run time.

Note:

Starting with version 2.0 you can define specialized message handlers which are nothing but special types of methods.

See Also:

Custom Message Handlers

Editing existing properties


Custom Message Handlers

You can now build a custom message handler automatically with Version 2.0.  You can override any number of standard windows messages by selecting the desired messages from the list box.  User defined messages are also supported, just enter a message name and an appropriate WM_USER offset value and click the add button.  When the component is built the appropriate message procedure declarations and code fragments are added to the source output.  If you are not familiar with message handlers refer to the Delphi Component Writers Guide pages 67, 68, 104, and 147-148.


Defining Event Handlers

To define an event handler, give it a name, select the type (probably TNotifyEvent) and give it a paramater list.  Don't include the parentheses in the paramater list, just 's : string' will do.  If your wondering what an event handler is refer to the Component Writer's Guide.  In fact if your wondering that at this point, you probably need to read the entire Guide before proceeding.

See Also:

Editing existing properties

Creating Message Handlers


Building the Output

Click the Build button or select Build Source Output from the menu.  The actual output is displayed on the Tab Page captioned 'Output'.  You can then add your code for methods, event handlers, etc. before saving the output to a file.


Adding Code

For your component to do anything really useful, you'll need to add the code to the method and event handler skeletons.  You can do that right on the output page before saving the finished source.

Note:

Component Builder builds all the code from scratch when the build button is clicked.  Make sure that you have defined all the properties, methods and events you'll need before adding any of your own code because if you go back and add another property, the custom code you've added will be lost on the rebuild.  You can, of course, add the new property manually in the code window.  Whenever I build a component, I use component builder to define my properties and methods, etc. and then save the output file and immediately jump into Delphi to finish the component.  The Delphi editor brings things to the table that Component Builder just doesn't offer like highlighting keywords, etc.


Saving Your Work

Before exiting Component Builder, you'll want to save your work.  Click the save button or select 'Build|Save .pas file' from the menu.  If you don't have a registered version of this product, you won't be able to save to a file.
The actual output file is named according to the unit name on the Class page.  You'll also be asked if you want to save the component specifications before exiting.  You should do so if you will need to retrieve the property, method and event definitions for later use with Component builder.


Installing New Components

There are two ways to install your newly created component.

1.	From the Delphi menu select Options|Install Components

2.	From the Component Builder menu select Build|Install New Component.  Component Builder does

the work for you.


WHAT IT IS
What it is ?

Component Builder will create all the necessary code for a component source file including underlying variable declarations, method and event handler declarations and property declarations.  It will build the code skeletons for methods, etc. as well as the declarations.  It saves you a LOT of typing and eliminates a lot of errors as well, but here's .....

What it ain't !

Component Builder will not read your mind and build you a tailor made component with all the functionality you envision.  You have to add the 'real' code to provide the functionality you want your component to have.


Product Support

You can contact me through Compuserve 76350,3301 for product support. I'll be happy to answer any questions.  If you find a bug, let me know I'll fix it.  If you have any suggestions for improvement, let me know.  If you're not a compuserve member leave me e-mail at 76350.3301@compuserve.com OR

jcta@mindspring.com.  Some sites on the web do not have the latest version of Component Builder.  If you are evaluating it and want the latest edition please visit my website and download it.  As I update Component Builder, I automatically send the latest version to all registered users.

You can contact me via postal mail or voice at:

John C. Taylor
3475 Holcomb Br Rd
Suite 202
Norcross, GA   30092

Phone (770)-449-6284

If you call my voice you may well get my voice mail, if so, leave me a message.  I really prefer to be contacted via e-mail.


How to Register

Registering by Credit Card

You can register this product by sending me $ 20 (US).  Compare that to the commercial products

costing ten to twenty times more.  Support the shareware concept !

If you are a compuserve member you can register online SWREG # 8257.  If you're not familiar with registering shareware through Compuserve, just GO SWREG and follow the instructions.

As soon as I am notified of your registration I will send you the registered version of Component Builder

via email.  I always get same day notification (mostly within minutes) of registrations.  If you register by credit card (see above) they also notify me that day so you'll have the registered version usually that same day.  If you can't accept files email, I'll have to go to the trouble of sending you a diskette and you'll have to wait for the snail mail.  If you're sending me a check, the registered version will be sent to you as soon as I receive your check (no waiting for it to clear).

Where to send money:

John C. Taylor
3475 Holcomb Br Rd
Suite 202
Norcross, GA  USA   30092


Visa and MasterCard Registration

For your convenience I have contracted NorthStar Solutions to process any registrations that you wish to place with your valid Visa or MasterCard.  The may be contacted for REGISTRATIONS ONLY at:

Voice:  1-800-699-6395 (10:00 am - 10:00 pm EST call from US only)
           1-803-699-6395 (10:00 am - 10:00 pm EST calls outside US)

FAX:    1-803-699-5465 (Available 24 hours. International orders encouraged).

E-mail:  America Online: STARMAIL     Compuserve: 71561,2751
            Internet: starmail@aol.com

When contacting Northstar tell them you are registering John Taylor's Component Builder and have your credit card number and expiration date handy.  Once they have notified me of your registration, I will distribute the registered version to you.

Important note:

NorthStar cannot provide any technical information or technical support for Component Builder.  For technical support contact the author (me).

Technical Support


Frequently Asked Questions

Q.  How do I install my newly created component ?

A.  From the Delphi menu choose 'Options|Install Components'.  Select the newly created component.  It will be the file name and path you entered in the unit name box on the Class page.  You can also select 'Install|Install new component' from CB's menu. If Delphi is not running, this item is disabled.

Q.  I defined my property and did a Build but I didn't see it on the output page.  What went wrong ?

A.  Don't forget to click the Add button to add the property to the list of Defined Properties.

Q.  How can I change a previously defined property ?

A.  Select and remove it from the list of defined properties.  Then
redefine it and add it back to the list.  If you have version 1.1 you can double click on the property, method or event, change the attributes and then click the add button.

Q.  How can I save my work before I'm ready to build the final output ?

A.  Select 'File|Save *.spc file' from the menu.


Other Topics

Adding Component Builder to Delphi's menu:

Select 'Install|Add to tools menu' from CB's menu to add Component Builder to the Delphi Tools menu.  If Delphi is already running, you won't see this on it's menu until you exit it and restart.

Installing the new component:

Select 'Install|Install new component' from the menu.  Delphi must be running for this item to be enabled.

Saving the component specifications:

To save the component specifications choose 'File|Save *.spc file' from the menu.  This does not create a useable output file but only saves the specifications for later retrieval.  Saved specifications include property, method and event handler definitions.

Retrieving component specifications:

From the menu choose 'File|Open *.spc file'.  Previously saved component specifications will be loaded from the spc file.


About this Help file

This help file is to get you started with Component Builder.  It is NOT a tutorial on how to write components.  If you're planning to write components for Delphi, you should be thoroughly familiar with the Component Writer's Guide that ships with Delphi.  Also the Component Writer's Help contains invaluable information that should be your standard reference when building a component.  This file does not attempt to explain such things as what is a virtual method, etc. and other technical details of component design.  Refer to the Guide for intricacies of component design.

See Also:

 Recommended Reading


Revision History

Version 1.1 changes:

New Features:

Editing existing properties, methods and events

Edit menu

Open button

Bug Fixes:

Function and procedure headers were not formatted correctly in the output window in version 1.0.  This has been fixed.

Note:

Previously built *.spc files may not produce the correct property types with version 1.1.  You will have to delete the property and then redefine it.

Version 1.2 changes:

Version 1.2 included only minor bug fixes

Version 2.0 changes:

New Features:

Support for standard properties and events

Creating custom message handlers

Source code formatting options

Version 2.1 changes:

Bug fix - multiple parameters were lost when redeclaring methods.

New Features:

When a property is declared with a data type of a class name (such as TStringList) the additional unit declaration is provided automatically when the source code is built.  The edit window allows the addition of additional uses clauses if needed by positioning the cursor at the appropriate place in the uses clause and clicking on the panel section captioned 'units'.

Version 2.2 changes:

New Features:

Source code comment and documentation features added to properties, methods and event handler pages.

Pointer check box added to property page to indicate a pointer to a data type.

Added support for indexed (array) properties.

Additional features added to style page.

Version 2.3 changes:

Fixed a bug that caused a GPF when descending from ancestors of certain types.

The panel click bar for unit names on the outpage has been removed.  Instead, I elected to include all available units in the uses clause.  I did this because Delphi's smartlinker only links in units if a reference to a type defined in that unit is made in the component.  This turned out to be much easier than trying to determine which unit was needed and causes the resulting .exe file to be smaller.  Note however, that if you have defined object types of your own, you will have to add that unit to the uses clause manually.  If I've missed one of the standard units, add it manually and let me know about it so I can add it to the next update.

Shortcut keys were added to the edit menu.

When a property is declared as an array property it should be either protected or public, NOT published.  Version 2.3 automatically assumes that the property is to be public (run time only) unless you check protected under the attributes section.

I blindly introduced the pointer check box in Version 2.2 at the request of a user.  Well... I'm not sure you can define a property as a pointer to a data type such as ^char since a property is itself a pointer.  The documentation is vague to me and I haven't successfully built a component with this type of property declaration.  If anybody knows for sure, let me know, I'll rip this out if needed.


Edit Menu

The edit menu has been changed.  Font, background color and wordwrap options have been moved to the Preferences submenu.  A printer font option has been added under Preferences.  The default is for the printer font to match the output window font.  You may choose the default printer font by checking that item, however it is the system font and in most cases it produces bold output which annoys many users.


Open Button

An open button has been added to the toolbar to speed the opening of *.spc files.


Standard properties and events

Version 2.0 of Component Builder displays the ancestor's standard properties on the properties page.  A new list box has also been added to the event handler page which displays the standard event handlers for the ancestor class.  When the build is performed the standard properties and events are included in the published section of the source code.


Source Code Formatting

While I can't anticipate everyone's style preferences, I did add a style page to Version 2.0.  You can select the number of spaces to indent and the number of lines you want to separate function and procedures.


F1ProjectGlossary2
Property Name

The property name can be any valid identifer. For example : Count